---
title: Cloudinary & Astro
description: Cloudinary를 사용하여 Astro 프로젝트에 이미지와 동영상 추가하기
sidebar:
  label: Cloudinary
type: media
stub: true
logo: cloudinary
i18nReady: true
---
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';

[Cloudinary](https://cloudinary.com)는 이미지 및 동영상 플랫폼이자 헤드리스 디지털 자산 관리자 (DAM)로, 콘텐츠 전송 네트워크 (CDN)에 자산을 호스팅하고 전송할 수 있는 서비스입니다.

Cloudinary에서 제공하는 경우, 배경 제거, 동적 자르기 및 크기 조정, 생성형 AI와 같은 도구를 사용하여 자산을 편집할 수 있는 Transformation API에 추가로 액세스할 수 있습니다.

## Astro에서 Cloudinary 사용

Cloudinary는 Astro 환경에 따라 사용할 수 있는 다양한 SDK를 지원합니다.

[Cloudinary Astro SDK](https://astro.cloudinary.dev/)는 이미지, 동영상, 업로드 컴포넌트를 포함한 기본 Astro 컴포넌트와 Astro 콘텐츠 컬렉션과 함께 사용할 수 있는 콘텐츠 로더를 제공합니다.

또는 Cloudinary [Node.js SDK](https://cloudinary.com/documentation/node_integration)와 [JavaScript SDK](https://cloudinary.com/documentation/javascript_integration)를 모두 사용하여 이미지의 URL을 생성할 수 있습니다. Node.js SDK는 Cloudinary API에 자산 업로드, 리소스 요청, 콘텐츠 분석 실행 등 추가 요청을 할 수 있습니다.

## 전제 조건

- 기존 Astro 프로젝트
- Cloudinary 계정

## Astro Cloudinary 설치

패키지 관리자에 적합한 명령을 실행하여 Cloudinary Astro SDK를 설치합니다:

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npm install astro-cloudinary
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm add astro-cloudinary
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn add astro-cloudinary
  ```
  </Fragment>
</PackageManagerTabs>

## 계정 구성

프로젝트의 루트에 새 `.env` 파일을 만들고 Cloudinary 자격 증명을 추가합니다:

```shell title=".env"
PUBLIC_CLOUDINARY_CLOUD_NAME="<클라우드 이름>"

// CldUploadWidget 또는 cldAssetsLoader를 사용하는 경우에만 필요합니다.
PUBLIC_CLOUDINARY_API_KEY="<API 키>"
CLOUDINARY_API_SECRET="<API 비밀>"
```

## Cloudinary 이미지 사용

이미지 데이터 (예: `src`, `width`, `alt`)를 `<CldImage>` 컴포넌트에 전달하여 `.astro` 컴포넌트에 이미지를 추가합니다. 이렇게 하면 이미지가 자동으로 최적화되고 Transformations API에 액세스할 수 있습니다.

```jsx title="Component.astro"
---
import { CldImage } from 'astro-cloudinary';
---
<CldImage
  src="<Public ID>"
  width="<Width>"
  height="<Height>"
  alt="<Description>"
/>
```

자세한 내용은 [Cloudinary의 `<CldImage>` 문서](https://astro.cloudinary.dev/cldimage/basic-usage)를 참조하세요.

## Cloudinary 동영상 사용

`.astro` 컴포넌트에 동영상을 추가하려면 `<CldVideoPlayer>`를 추가하고 적절한 속성을 전달하세요. 이 컴포넌트는 [Cloudinary 비디오 플레이어](https://cloudinary.com/documentation/cloudinary_video_player)를 사용하여 동영상을 자동으로 최적화하고 임베드합니다.

```jsx title="Component.astro"
---
import { CldVideoPlayer } from 'astro-cloudinary';
---
<CldVideoPlayer
  src="<Public ID>"
  width="<Width>"
  height="<Height>"
/>
```

자세한 내용은 [Cloudinary의 `<CldVideoPlayer>` 문서](https://astro.cloudinary.dev/cldvideoplayer/basic-usage)를 참조하세요.

## Cloudinary 업로드 활성화

웹사이트나 앱의 UI에서 파일 업로드를 활성화하려면 [Cloudinary Upload Widget](https://cloudinary.com/documentation/upload_widget)을 임베드하는 `<CldUploadWidget>`을 추가합니다.

다음 예시는 서명되지 않은 [Upload Preset](https://cloudinary.com/documentation/upload_presets)을 전달하여 서명되지 않은 업로드를 허용하는 위젯을 만듭니다:

```jsx title="Component.astro"
---
import { CldUploadWidget } from 'astro-cloudinary';
---
<CldUploadWidget uploadPreset="<Upload Preset>">
  <button>Upload</button>
</CldUploadWidget>
```

서명된 업로드에 대한 [가이드 및 예시](https://astro.cloudinary.dev/clduploadwidget/signed-uploads)는 Astro Cloudinary 문서에서 확인할 수 있습니다.

자세한 내용은 [Cloudinary의 `<CldUploadWidget>` 문서](https://astro.cloudinary.dev/clduploadwidget/basic-usage)를 참조하세요.

## Cloudinary 콘텐츠 로더

Cloudinary Astro SDK는 콘텐츠 컬렉션을 위한 Cloudinary 자산을 불러오는 `cldAssetsLoader` 콘텐츠 로더를 제공합니다.

이미지 또는 동영상 컬렉션을 불러오려면 `loader: cldAssetsLoader ({})`의 `folder`를 설정합니다 (필요한 경우):

```jsx title="config.ts"
import { defineCollection } from 'astro:content';
import { cldAssetsLoader } from 'astro-cloudinary/loaders';

export const collections = {
  assets: defineCollection({
    loader: cldAssetsLoader({
      folder: '<Folder>' // 선택 사항, 루트 디렉터리를 불러오지 않음
    })
  }),
}
```

그런 다음 [`getCollection()` 또는 `getEntry()` 쿼리 함수](/ko/guides/content-collections/#컬렉션-쿼리)를 사용하여 컬렉션에서 하나 이상의 이미지 또는 동영상을 선택할 수 있습니다.

자세한 내용은 [Cloudinary의 `cldAssetsLoader` 문서](https://astro.cloudinary.dev/cldassetsloader/basic-usage)를 참조하세요.

## Cloudinary 이미지 URL 생성

Astro Cloudinary SDK는 이미지의 URL을 생성하고 사용하기 위한 `getCldOgImageUrl()` 헬퍼를 제공합니다. 이미지를 표시하기 위해 컴포넌트 대신 URL이 필요할 때 이 함수를 사용하세요.

URL의 일반적인 용도 중 하나는 소셜 미디어 카드를 위한 `<meta>` 태그의 오픈 그래프 이미지입니다. 이 헬퍼는 컴포넌트와 마찬가지로 Cloudinary transformations에 액세스하여 모든 페이지에 대한 동적이고 고유한 소셜 카드를 만들 수 있습니다.

다음 예시는 소셜 미디어 카드에 필요한 `<meta>` 태그와 `getCldOgImageUrl()`을 사용하여 오픈 그래프 이미지를 생성하는 방법을 보여줍니다:

```jsx title="Layout.astro"
---
import { getCldOgImageUrl } from 'astro-cloudinary/helpers';
const ogImageUrl = getCldOgImageUrl({ src: '<Public ID>' });
---
<meta property="og:image" content={ogImageUrl} />
<meta property="og:image:secure_url" content={ogImageUrl} />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
<meta property="twitter:title" content="<Twitter Title>" />
<meta property="twitter:card" content="summary_large_image" />
<meta property="twitter:image" content={ogImageUrl} />
```


Cloudinary 문서에서 [Cloudinary 소셜 미디어 카드 템플릿](https://astro.cloudinary.dev/templates/social-media-cards)을 찾으세요.

자세한 내용은 [Cloudinary의 `getCldOgImageUrl()` 문서](https://astro.cloudinary.dev/getcldogimageurl/basic-usage)를 참조하세요.

## Node.js에서 Cloudinary 사용

Astro Node.js 환경에서 작업할 때, 보다 복잡한 자산 관리, 업로드 또는 분석이 필요한 경우 Cloudinary Node.js SDK를 사용할 수 있습니다.

패키지 관리자에 적합한 명령을 실행하여 Cloudinary Node.js SDK를 설치합니다:

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npm install cloudinary
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm add cloudinary
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn add cloudinary
  ```
  </Fragment>
</PackageManagerTabs>

`.env` 파일에 다음 환경 변수를 추가합니다:

```shell title=".env"
PUBLIC_CLOUDINARY_CLOUD_NAME="<Your Cloud Name>"
PUBLIC_CLOUDINARY_API_KEY="<Your API Key>"
CLOUDINARY_API_SECRET="<Your API Secret>"
```

Astro 컴포넌트의 펜스 사이에 다음 코드를 추가하여 새 Cloudinary 인스턴스로 계정을 구성합니다:

```js title="Component.astro"
---
import { v2 as cloudinary } from "cloudinary";

cloudinary.config({
  cloud_name: import.meta.env.PUBLIC_CLOUDINARY_CLOUD_NAME,
  api_key: import.meta.env.PUBLIC_CLOUDINARY_API_KEY,
  api_secret: import.meta.env.CLOUDINARY_API_SECRET,
});
---
```

이렇게 하면 이미지, 동영상 및 기타 지원되는 파일과 상호 작용할 수 있는 모든 Cloudinary API에 액세스할 수 있습니다.

```js title="Component.astro"
await cloudinary.uploader.upload('./path/to/file');
```

[Astro Forms와 Cloudinary Node.js SDK를 사용하여 파일을 업로드하는 방법](https://www.youtube.com/watch?v=DQUYMyT2MTM)을 알아보세요.


## 공식 리소스

- [Cloudinary Astro SDK](https://astro.cloudinary.dev/)
- [Cloudinary Node.js SDK](https://cloudinary.com/documentation/node_integration)
- [Using Cloudinary with Astro (YouTube)](https://www.youtube.com/playlist?list=PL8dVGjLA2oMqnpf2tShn1exf5GkSWuu5-)
- [Code Examples Using Cloudinary Astro SDK (GitHub)](https://github.com/cloudinary-community/cloudinary-examples/tree/main/examples/astro-cloudinary)
